MacFormat 1994 August/August CD.bin/Shareware/Programming/Help on Wheels ƒ/HoW Developer’s Kit 1.1/HoWSample/HoWSample Help/HoWSample Help.rsrc/STR#_1029.txt

Text File | 1994-06-05 | 9.0 KB | 363 lines



pascal OSErr HoWOpen (const FSSpec *helpFile);

*/

when calculating the system heap requirement for your 'sysz' resource.

extensions, because it uses the Notification Manager; allow 5000 bytes

always used.  This may be called by 'INIT' logic in control panels or

checking is not performed, and the current script's current language is

opened (as for a background-only application calling HoWDisplay).  Version

the server is absent, a TeachText copy is created on the desktop and

applications; applications should use HoWRegister instead (see above).  If

help file.  This method is suggested for use by programs which are not

/* Launch the help server, if necessary, to open and display the given







pascal OSErr HoWDeregister (void);

before it exits, the server will deregister it automatically. */

/* Deregister with the help server.  If the client fails to deregister







pascal OSErr HoWDisplay (short tag, Boolean casual);

to the foreground unless they are hidden before this call. */

foreground.  Note that modal dialogs will prevent the server from coming

in the foreground; a non-casual display always brings the server to the

displaying this client's help file.  A casual display always leaves the client

running in the background, with the "follow" option in effect, and already

desktop.  A casual display is effective only if the server is started and

in which case no alerts appear, and the document is created on the

TeachText and open it for viewing, unless the client is background-only,

absent, the user sees an alert offering to save a readable copy using

"casual" is false, this will attempt to start the server; if the server is

last seen position is retained.  If the server is not already started, and

/* Display the help file at the indicated tag position.  If "tag" is zero, the







                          HoWHandlerProcPtr handler);

                          LangCode defaultLanguage, Boolean startServer,

pascal OSErr HoWRegister (const FSSpec *helpFile, short version,

client does not support them. */

noAppleEventsErr.  The Help event handler is optional; pass nil if the

codes listed above; the expected error code under System 6 is

starts by some other method.  Gestalt checks may result in other error

deferred until the first non-casual display (see below) or until the server

return code is noErr, meaning that the actual registration has been

"startServer" is false (which it should be for most clients), the usual

HoWDisplay below).  If the server is not already started, and

noServerApplErr, a non-fatal code returned for your information (see

server, which may result in many OS error codes, as well as

started, and "startServer" is true, HoWRegister will try to start the

client can switch to another help file.  If the server is not already

to use its own language over "defaultLanguage".  By re-registering, the

nor for langEnglish, noMasterResErr is returned.  The server will prefer

file for the current script's current language, nor for "defaultLanguage",

wrongVersionErr is returned.  If there is no master resource in the help

resource, and the version (first word) does not match "version",

file, including the main application file.  If the help file has a 'vers'(1)

/* Register or re-register with the help server.  The help file may be any







                              short aliasResID, FSSpecPtr helpFile);

                              short applicationFileRefNum,

pascal OSErr HoWFindHelpFile (short preferencesFileRefNum,

the preferences file. */

same value, and the application file will be treated as though it were also

maintain a separate preferences file, set both resource file IDs to the

until a later fast search successfully finds the help file.  If you do not

is not repeated; this note remains until the preferences file is deleted, or

file.  A failed exhaustive search is noted in the preferences file so that it

one exhaustive search will be done on the alias record in the application

alias resource if present.  If the help file cannot be found by a fast search,

application file, so it can take advantage of relative information in the

possible.  The application file is not changed.  Resolution is relative to the

changed by UpdateAlias, is written back to the preferences file if

preferences file or cannot be resolved.  The alias record, possibly

file with ID "applicationFileRefNum" if the resource does not exist in the

in the resource file with ID "preferencesFileRefNum", or in the resource

/* Find the help file referenced by the 'alis' resource with ID "aliasResID"







typedef pascal void (*HoWHandlerProcPtr) (short id);

the tag associated with the clicked text. */

/* The Help event handler receives an event id which is the negative of







descriptions.

follow along in the HoWSample source code as you read these function

and when to call them, quoting from the C header file.  You may want to

This subsection describes exactly what the HoWLib functions do, and how




xHoWLib Client Interface Library Functions







server’s Preferences dialog.

ineffective if the user has not selected the “follow” option in the

is not already displaying the client’s help file.  Fourth, they are

the server into the foreground.  Third, they are ineffective if the server

they do not start the server if it isn’t running.  Second, they do not bring

Specifically, casual displays are different in the following ways:  First,



effectively taking control of the help display.

mechanism allows the client to use the server’s optional “follow” mode,

makes the call more of a hint to the server, and less of an order.  This

selects a menu item or clicks on a dialog item.  Setting “casual” to true

user action.  HoWSample requests a casual display whenever the user

function is always false when HoWSample calls it in reaction to a direct

help using casual displays.  The “casual” argument to the HoWDisplay

HoWSample also demonstrates how you can implement context-sensitive





tag values, demonstrating how a client can index the help file.

Subsidiary items in the Help menu cause calls to HoWDisplay with other

dialog is open, some tag value appropriate to the cursor location.

presses the Help key, it calls HoWDisplay with “tag” set to 0, or if a

client practices.  Whenever the user selects the main Help menu item or

HoWSample is a very simple client application which demonstrates good




xCasual Displays







puts them in a new directory.

large for TeachText to open, the engine breaks it into several files and

engine creates the file and opens it automatically.  If the file would be too

to save the help text as a TeachText document.  If the user agrees, the

can’t be found on any mounted volume, the engine posts an alert, offering

If you call HoWDisplay when the server is not started, and the server



invoking your handler, if you have one.

application to its Help menu.  The engine also takes care of Help events by

running, the engine senses this, and makes sure that the server adds your

If the server is started by some other method while your application is

purgeable code segment named “HoWLib,” manages these details for you.

while your application is running.  The client engine, contained in a

whether it’s running already, or what to do if the user exits the server

server.  Your application doesn’t have to care where the server is, or

The client engine handles the rest of the relationship between client and



latter, less obnoxious, option.

availability is critical to your application, you will usually choose the

immediately, or deferring until the first display.  Unless the server’s

When you register, you have the option of starting the server



for display nor for Help events.

necessary).  It cannot communicate with the server using tags, neither

call HoWOpen to tell the server to open the help file (starting the server if

It can call HoWFindHelpFile to find its help file if it is separate, and it can

If your program is not an application, it cannot use client engine functions.






the rules.)


(Click this hot button to hear what famous Apple product doesn’t play by

event, which is generally good practice.

when you receive any high-level event that isn’t known not to be an Apple

Apart from that, the only requirement is to call AEProcessAppleEvent

in response to menu, mouse, and key events, and deregister on exit.

application will generally find its help file and register on entry, display

functions, HoWRegister, HoWDisplay, and HoWDeregister.  Your

functions, HoWFindHelpFile and HoWOpen, and three client engine

The interface, described in the next subsection, consists of two utility




xThe Client Engine









server, with the help of the HoWLib client interface library.

This section explains how a client conducts its relations with the help








åClient-Server Relations


@



@